<html>
<head><meta charset="utf-8"><title>Infrastructure for document translation · rustdoc · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/index.html">rustdoc</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html">Infrastructure for document translation</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="239838100"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/239838100" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Charles Lew <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#239838100">(May 22 2021 at 02:57)</a>:</h4>
<p>Hello, i'm thinking about doing something inline with <a href="https://github.com/rust-lang/community-localization/issues/5">https://github.com/rust-lang/community-localization/issues/5</a> .<br>
Before doing so, i'd like some basic directional review.</p>



<a name="239840745"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/239840745" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#239840745">(May 22 2021 at 03:43)</a>:</h4>
<p><span class="user-mention" data-user-id="116458">@Charles Lew</span> this is a giant feature, nothing about it is simple</p>



<a name="239840746"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/239840746" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#239840746">(May 22 2021 at 03:43)</a>:</h4>
<p>I would start with an RFC maybe</p>



<a name="239872863"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/239872863" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> GuillaumeGomez <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#239872863">(May 22 2021 at 13:27)</a>:</h4>
<p>Oh, the translation is back</p>



<a name="239872904"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/239872904" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> GuillaumeGomez <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#239872904">(May 22 2021 at 13:28)</a>:</h4>
<p>for the translation to be handled by rustdoc, I think we need to be able to generate doc from an external source</p>



<a name="239872917"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/239872917" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> GuillaumeGomez <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#239872917">(May 22 2021 at 13:28)</a>:</h4>
<p>like a big file which is used as reference for all API entries</p>



<a name="240007996"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/240007996" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Charles Lew <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#240007996">(May 24 2021 at 05:31)</a>:</h4>
<p>I decide to try if i can come up with something that works together well with mdbook first. I'll revisit <code>rustdoc</code> part after that.</p>



<a name="241701518"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241701518" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Charles Lew <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241701518">(Jun 06 2021 at 17:28)</a>:</h4>
<p>Continuing from the topic of <a href="#narrow/stream/226068-t-community.2Fl10n/topic/mdbook.20localization.20.282nd.20try.29">https://rust-lang.zulipchat.com/#narrow/stream/226068-t-community.2Fl10n/topic/mdbook.20localization.20.282nd.20try.29</a> ,  now we all agree rustdoc should use key-indexed translations. The question is that, if the content itself is not a good enough key (which i was exploring). what could be better?</p>



<a name="241745265"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241745265" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> GuillaumeGomez <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241745265">(Jun 07 2021 at 08:44)</a>:</h4>
<p>I think <span class="user-mention" data-user-id="132040">@Manish Goregaokar</span> meant that the items and not the documentation itself should be used as key (please correct me if I misunderstood). This is something I planned to do, but that will require a LOT of work on rustdoc to allow to have documentation written in files outside the code and then imported back. Funnily enough, I wrote a crate which allows to extract and put back doc comments (from a markdown file) with the <code>rustdoc-stripper</code> crate. However, I really don't recommend it for big projects and certainly not for rustdoc in general.</p>



<a name="241755710"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241755710" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Charles Lew <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241755710">(Jun 07 2021 at 10:28)</a>:</h4>
<p>thanks!</p>



<a name="241756107"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241756107" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Charles Lew <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241756107">(Jun 07 2021 at 10:32)</a>:</h4>
<p>I'm also still a little curious what's so bad about using the documentation itself as the key. I've participated in rust annual survey translation for a few times, and we've always been doing this.(Translating paragraph-by-paragraph)</p>
<p>Is it concerns about ambiguities that make people feel bad about it?</p>



<a name="241786367"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241786367" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> GuillaumeGomez <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241786367">(Jun 07 2021 at 14:40)</a>:</h4>
<p>It makes the translation much harder, there is no more "continuity" between paragraphs, and a few more reasons that I don't remember</p>



<a name="241788368"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241788368" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Charles Lew <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241788368">(Jun 07 2021 at 14:52)</a>:</h4>
<p>Well, taking <a href="https://github.com/crlf0710/rust-bookshelf-l10n/blob/master/reference-l10n/l18n/introduction.md">this as an example</a>. The continuity is still preserved, since neighboring paragraphs are just a few lines away...</p>



<a name="241846866"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241846866" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Manish Goregaokar <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241846866">(Jun 07 2021 at 21:58)</a>:</h4>
<p><span class="user-mention" data-user-id="116458">@Charles Lew</span> yeah what <span class="user-mention" data-user-id="210316">@GuillaumeGomez</span> said is correct, I'd say that the doc items should work as keys. So perhaps the path, or something, but annoyingly there's ambiguity when you have reexports and such</p>



<a name="241846924"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241846924" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Manish Goregaokar <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241846924">(Jun 07 2021 at 21:59)</a>:</h4>
<p><span class="user-mention" data-user-id="116458">@Charles Lew</span> documentation itself as a key is terrible because the documentation _changes_. the survey works fine because we take great care to _freeze_ the english version before handing it off to translators</p>



<a name="241846946"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241846946" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Manish Goregaokar <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241846946">(Jun 07 2021 at 21:59)</a>:</h4>
<p>"use the text itself as a key" is an older technique (used by gettext, etc) that has largely been obsoleted</p>



<a name="241847200"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241847200" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Manish Goregaokar <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241847200">(Jun 07 2021 at 22:01)</a>:</h4>
<p>the way I see rustdoc's thing going is that you have one cli option to export each doc item in rustdoc to a key-value pair, with uniquely named keys, and another cli option that can _take_ all these key-value pairs and "replace" docs</p>



<a name="241847274"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241847274" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Manish Goregaokar <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241847274">(Jun 07 2021 at 22:01)</a>:</h4>
<p>I'm thinking that we basically have one json or ftl or whatever file per src file, to limit ambiguity, and then the keys are named something sufficiently disambiguating (fully qualified relative path?)</p>



<a name="241847331"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241847331" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Manish Goregaokar <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241847331">(Jun 07 2021 at 22:02)</a>:</h4>
<p>i'd startt with json or something</p>



<a name="241847359"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241847359" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Manish Goregaokar <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241847359">(Jun 07 2021 at 22:02)</a>:</h4>
<p>because in the case of rustdoc we don't need fancy i18n features like plurals and stuff, it's pure textual replacement</p>



<a name="241867549"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241867549" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Charles Lew <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241867549">(Jun 08 2021 at 03:42)</a>:</h4>
<p><span class="user-mention silent" data-user-id="132040">Manish Goregaokar</span> <a href="#narrow/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation/near/241846946">said</a>:</p>
<blockquote>
<p>"use the text itself as a key" is an older technique (used by gettext, etc) that has largely been obsoleted</p>
</blockquote>
<p>Thank you for the insights of this!</p>



<a name="241867883"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241867883" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Charles Lew <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241867883">(Jun 08 2021 at 03:51)</a>:</h4>
<p>I feel something compatible with markdown parser would be nice. When doing the actual translation it would be nice if the newly written translated markdown doc comments can get a side-preview on-the-fly.</p>



<a name="241883611"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/Infrastructure%20for%20document%20translation/near/241883611" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> GuillaumeGomez <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/Infrastructure.20for.20document.20translation.html#241883611">(Jun 08 2021 at 08:09)</a>:</h4>
<p><code>rustdoc-stripper</code> is compatible with markdown so it's definitely a possibility. And in addition to that, I find markdown simpler to read/edit and you can add comments. But it's personal preference. :)</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>